**Table of Contents**

- [Troubleshooting](#troubleshooting)
- [Download Plover](#download-plover)
- [Migrating from v3 to v4](#migrating-from-v3-to-v4)
- [Installation](#installation)
  - [Install Plover on Windows](#install-plover-on-windows)
  - [Install Plover on Mac](#install-plover-on-mac)
  - [Install Plover on Linux](#install-plover-on-linux)
    - [Allowing Access to Serial Ports](#allowing-access-to-serial-ports)
    - [Error relating to xcb](#error-relating-to-xcb)
    - [Wayland](#wayland)
    - [Install Plover on Arch Linux distribution](#install-plover-on-arch-linux-distribution)
    - [Install Plover on Gentoo Linux distribution](#install-plover-on-gentoo-linux-distribution)
- [Setting up my machine](#setting-up-my-machine)
- [For developers: running from source](#for-developers-running-from-source)

## Troubleshooting

If you get stuck, you can:

- Check the [troubleshooting guide.](Troubleshooting:-Common-Issues)
- Search for your problem in our [issue tracker](https://github.com/openstenoproject/plover/issues) and our [Discussions forum.](https://github.com/openstenoproject/plover/discussions)
- If you can't find your particular problem, [open a support request](https://github.com/openstenoproject/plover/issues/new/choose) or [start a Discussion.](https://github.com/openstenoproject/plover/discussions/new)

We also have a [Plover Discord Server](https://discord.gg/0lQde43a6dGmAMp2), the [steno community](Links-to-the-Steno-Community), and a [GitHub Discussions forum](https://github.com/openstenoproject/plover/discussions) if you have a general idea or discussion topic.

## Download Plover

_**Note:** It is currently recommended to download the unreleased Plover version 4 even if it is not considered "stable" yet. Version 3 is outdated and may not work on some operating systems and contains known bugs._

**[Download the latest recommended release 🚀](https://github.com/openstenoproject/plover/releases/latest)**

See which file to download and how to install depending on your operating system:

- [Windows](#install-plover-on-windows)
- [Linux](#install-plover-on-linux)
- [Mac](#install-plover-on-mac)

_You can also get in-development versions of Plover by downloading the [continuous release](https://github.com/openstenoproject/plover/releases/tag/continuous) or by visiting [releases.](https://github.com/openstenoproject/plover/releases)_

## Migrating from v3 to v4

**Backing up your configuration:** Your version 3 configuration file can be read by version 4, but once version 4 is launched it will overwrite the configuration file with a new format, which means that version 3 will no longer have your settings. You can back up your `plover.cfg` in case you need to go back to version 3.

**Dictionary updates:** The dictionary has seen some upgrades over time, and by default Plover will not overwrite old versions of dictionaries. See the [guide on upgrading the dictionaries to the newest version.](Upgrading-V3-Dictionaries)

## Installation

Each release has files for all the operating systems we support. You only need the files that are relevant to your operating system

--------------------

### Install Plover on Windows

Plover is available as an installer (recommended) or as a portable ZIP, useful for running off of a USB stick or with restricted permissions.

**Installer:** Download the "Windows: Installer", launch it, and follow the instructions to install Plover. You may need to [grant permissions for the app to bypass Windows Defender SmartScreen.](https://www.windowscentral.com/how-disable-smartscreen-trusted-app-windows-10)

**Portable ZIP:** Download the "Windows: Portable ZIP" and **extract the entire folder** inside to the location that you'd like to run Plover from. Inside the folder, run `plover.exe` to start Plover.

--------------------

### Install Plover on Mac

1. Download the "macOS: Disk Image" file under "Assets" from the [releases page](https://github.com/openstenoproject/plover/releases).
1. Open the `.dmg` file.
1. In the mounted disk, drag the `Plover.app` to your `Applications` folder.
1. Open the Applications folder, and [follow the guide to launch a program from an unidentified developer.](https://support.apple.com/en-ca/guide/mac-help/mh40616/mac)
1. Open `System Preferences > Security & Privacy > Privacy > Accessibility`.
1. Click the "+" Button, and go to your applications and select `Plover.app`.

If you use a keyboard instead of a steno machine, Plover needs [Assistive Device Permissions](https://support.apple.com/en-ca/guide/mac-help/mh43185/mac). From the Catalina version of macOS, you may need to enable the `Plover` app under Security & Privacy > Privacy > Accessibility.

Plover is set up! You can run Plover like you would any other application.

> **Note**: Other "keyboard helper"-type applications (e.g. Karabiner Elements and text expanders) may interfere with Plover.

If you have [**Homebrew Cask**](https://caskroom.github.io/) installed on your system, you can run `brew install --cask plover` at the command-line.

--------------------

### Install Plover on Linux

[(archlinux)](installation-guide#install-plover-on-arch-linux-distribution), [(gentoo)](installation-guide#install-plover-on-gentoo-linux-distribution)

An [AppImage](http://appimage.org/) is provided: it includes all the necessary dependencies and should run on most x86 64-bits distributions. To use it:

- Download it
- [Make it executable](http://discourse.appimage.org/t/how-to-make-an-appimage-executable/80)
- Launch it like a standard executable

> **Note**: you can install the AppImage for your current user (and register Plover in your standard applications menu) by executing it with the `--install` flag. If you had previously installed another AppImage version of Plover, it will be automatically uninstalled and replaced.

#### Allowing Access to Serial Ports

For devices such as the Georgi and Tiny Mod which have serial modes (Gemini PR, or TX Bolt), you will have to add yourself to the `uucp` or `dialout` groups depending on your distro. These are the owners of `/dev/ttyACM*`, which is usually where your keyboard will show up. You can run `ls -l /dev/ttyACM*` when your keyboard is plugged in to find out which group owns the port.

To add a user to a group, you can use the command `sudo usermod -aG <group> <user>`. You will need to restart your session for the changes to apply.

For example: `sudo usermod -aG dialout bob` or `sudo usermod -aG uucp sue`.

#### Error relating to xcb

If the following error occurs when running the AppImage:

> Could not load the Qt platform plugin "xcb" in "" even though it was found. This application failed to start because noQt platform plugin could be initialized. Reinstalling the application may fix this problem.

Ensure that `libxcb`, `xcb-util` and `qt5-qtstyleplugins` are installed (or whatever the equivalent packages are on your distro).

If the error still persists, run the following:

`./plover.AppImage -s plover_plugins install -v 'PyQt5==5.14.2' 'PyQt5-sip==12.7.2'`

Note that the exact name of the AppImage will change depending on which version you install.

#### Wayland

Plover does not currently support Wayland [(issue #1050)](https://github.com/openstenoproject/plover/issues/1050). Wayland is used by default in many distributions — you'll need to switch back to X11.

--------------------

#### Install Plover on Arch Linux distribution

Two AUR packages are provided:

1. [plover](https://aur.archlinux.org/packages/plover/) for the latest stable release
2. and [plover-git](https://aur.archlinux.org/packages/plover-git/) for the current `master`

Note: the plugins manager is not part of `plover-git`, and is available as a [separate package](https://aur.archlinux.org/packages/plover_plugins_manager/).

--------------------

#### Install Plover on Gentoo Linux distribution

Currently, only a git ebuild for the `master` branch is provided.

[Personal overlay.](https://framagit.org/3/ebuilds) (out of date dependencies)

--------------------

## Setting up my machine

Initially, Plover is set up to use your computer keyboard as a steno machine. If you have a steno machine, you'll need to configure Plover to look for your machine. Please check the [Supported Hardware page](Supported-Hardware) to find instructions specific to your machine.

## For developers: running from source

If you want to build from source (e.g. if you are a developer), follow the guide for your operating system:

- [`plover/windows`](https://github.com/openstenoproject/plover/tree/master/windows)
- [`plover/linux`](https://github.com/openstenoproject/plover/tree/master/linux)
- [`plover/osx`](https://github.com/openstenoproject/plover/tree/master/osx)

